home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Technical Documentation / Sample Code / DTS.Lib & Samples / DTS.Lib / =Using CtlHandler.c < prev    next >
Encoding:
Text File  |  1992-10-22  |  7.3 KB  |  164 lines  |  [TEXT/MPS ]
  1. ***** CtlHandler.c usage documentation *****/
  2.  
  3. Purpose:  To simplify and standardize control handling within a window.
  4.  
  5.  
  6. This code implements the new 7.0 human-interface standards for both
  7. TextEdit and List controls.  These standards include the following features:
  8.  
  9. 1) Tabbing between TextEdit and List controls within a window.
  10. 2) Displaying what item is active.  The active TextEdit item is indicated
  11.    by either a blinking caret, or a selection range.
  12. 3) List positioning via the keyboard.  Entries on the keyboard automatically
  13.    select and display the closest List item.  Also, the up and down arrows
  14.    scroll through the list.
  15. 4) Document window scrollbars are handled.
  16.  
  17.  
  18. The main call for handling the control events is:
  19.  
  20. short    IsCtlEvent(WindowPtr window, EventRecord *event, ControlHandle *ctl, short *action);
  21.  
  22. This call handles the following:
  23.     1) Document scrolling.
  24.     2) TextEdit control events.
  25.     3) List control events.
  26.     4) Tabbing between TextEdit and list controls.
  27.     5) Displaying the selected TextEdit or List control.
  28.     6) Buttons.
  29.     7) Radio buttons.
  30.     8) Check boxes.
  31.     9) Popups.
  32.  
  33. The document content is scrolled automatically.  The updateRgn is set to include the
  34. area scrolled into view and the window update procedure is automatically called.
  35.  
  36. TextEdit and List control events are completely handled.  Since the controls are just
  37. containers for TERecords or ListRecords, all other access is up to the application.
  38.  
  39. Simple buttons are simply tracked.
  40.  
  41. Radio buttons are updated to reflect the new selection.  Radio buttons are handled as
  42. families.  The refCon field holds the family number.  For any given family, there can
  43. only be one selected radio button.  When a new one is clicked on, the old selected
  44. radio button is deselected automatically.
  45.  
  46. Check boxes are simply toggled on and off, as there is no family relationship between
  47. checkboxes.
  48.  
  49. Popups are simply tracked.  To determine what the popup choice is, the popup control
  50. value will have to be retreived.
  51.  
  52. The return value of IsCtlEvent is non-zero if the event was handled.  The values are
  53. as follows:
  54.  
  55. -1:        IsCtlEvent() scrolled the document.  the constant kScrollEvent is defined as -1 for
  56.         this purpose.
  57. 0:        IsCtlEvent didn't handle the event.
  58. 1-N:    The control number of the control that handled the event.  Remember that a TextEdit
  59.         control may actually consist of up to 3 controls.  There is the main container
  60.         control for the TERecord.  There may also be 1 or 2 scrollbar controls that are
  61.         related to the TERecord.  The control number reflects which control was hit.  This
  62.         allows determination as to whether or not the scrollbar was hit.
  63.  
  64. Just because a control number was returned doesn't mean that a control handle was returned.
  65. If an inactive scrollbar is clicked on, then FindControl() returns nil, instead of the
  66. control handle (really).  The control that is returned is what FindControl returns, and
  67. therefore it is possibly nil.
  68.  
  69. For TextEdit and List controls, IsCtlEvent simply calls CTEClick(), CTEKey(), CLClick() or
  70. CLKey().  The value returned as the action depends on which function was called.  The true/false
  71. returned by these functions as to whether or not the control handled the event is expanded to
  72. be the control number.  If false is returned by any of these functions, then IsCtlEvent()
  73. returns 0 for the control number.
  74.  
  75. IsCtlEvent() has no way of determining if you are actually using TextEdit or List controls.
  76. Since it has to make function calls service these controls, code may get linked into your
  77. application that you don't need.  To prevent this, IsCtlEvent() calls the appropriate
  78. functions by function pointer.  The default functions are just stub functions that return
  79. appropriate results as if there were no such controls.  This allows IsCtlEvent() to handle
  80. the case where these controls aren't used without linking in a bunch of code.
  81.  
  82. So what about the case where you DO want to use these controls?  To create one of these
  83. controls, you have to call either CTENew() or CLNew(), for TextEdit and List controls,
  84. respectively.
  85.  
  86. When CTENew() is called, it calls CTEInitialize().  CTEInitialize() replaces all
  87. of the stub function procedure pointers with pointers to the actual functions.
  88. If you call CTENew(), then CTENew() will get linked in.  Since CTENew() calls
  89. CTEInitialize(), CTEInitialize() will get linked in.  Since it references the actual
  90. code, the actual code will get linked in.  This allows you to not have to worry about
  91. specific implementations linking in too much code.  If you call it, it will link.  The
  92. above process is also done for List controls.
  93.  
  94.  
  95.  
  96. The remaining functions aren't nearly as interesting, but they can prove to be useful.
  97. These are:
  98.  
  99. short    CNum2Ctl(WindowPtr window, short ctlNum, ControlHandle *ctl);
  100.  
  101. This function converts a control number to a control handle.  The function
  102. simply walks the window's control list counting down until it has reached
  103. the right control number.  It also returns the number of controls traversed.
  104. While often this will be the same as the control number passed in, if the
  105. number passed in is greater than the number of controls in the list, then
  106. the number returned is the number of controls in the list. */
  107.  
  108.  
  109.  
  110. short    Ctl2CNum(ControlHandle ctl);
  111.  
  112. Convert a control handle to a control number.  This allows you to convert what
  113. is normally a runtime variable into something that can be equated to a constant,
  114. thus allowing you to code your control handling into case statements.
  115.  
  116.  
  117.  
  118. void    DoCtlActivate(WindowPtr window)
  119.  
  120. This reactivates the TextEdit or List control that was active for a particular window.
  121. When a window is moved from the front, the controls are supposed to become inactive.
  122. This is handled, but the control that was last active for a window is remembered.
  123. When the window is brought to the front, that particular control can be reactivated
  124. by calling DoCtlActivate().
  125.  
  126.  
  127.  
  128. short    GetButtonVariant(ControlHandle ctl);
  129.  
  130. This returns the variant type for a button control, independent of which system software
  131. you are running.
  132.  
  133.  
  134.  
  135. void    GetCheckBoxValues(WindowPtr window, Boolean checkBoxVal[]);
  136.  
  137. This returns all of the checkbox values for a window all at once.  The array has
  138. to have at least as many elements as there are checkboxes in the window.  Once
  139. this call is made, you can simply reference the value in the appropriate position
  140. in the array.
  141.  
  142.  
  143.  
  144. short    GetRadioButtonChoice(WindowPtr window, short famNum);
  145.  
  146. Given a particular family number, return which radio button is the currently selected
  147. button.  If the requested family isn't found, or there are no selected radio buttons
  148. in the family, -1 is returned.  If the family is found, the control number of the the
  149. selected radio button minus the control number of the first in the family is returned.
  150. This means that for most situations, you will simply get an integer from 0-N for the
  151. radio button selection, as in most cases, the radio buttons will be sequential in the
  152. control list.
  153.  
  154.  
  155.  
  156. short    HandleScrollEvent(WindowPtr window, EventRecord *event, ControlHandle *retCtl, short *action);
  157.  
  158. This is the function that IsCtlEvent uses to handle the document scrolling.  You can
  159. call it directly if you wish.  You may wish to do this if your windows don't have any
  160. content controls, and all you need is the document scrolling support.  By calling it
  161. directly, instead of by calling it through IsCtlEvent(), you will link in less code
  162. into your application.
  163.  
  164.